home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / altrn234.zip / ALTERN22.DOC next >
Text File  |  1988-12-02  |  16KB  |  346 lines
  1.  
  2.  
  3.  
  4.                              ALTERN VERSION 2.2
  5.  
  6.                   ALTERNATE AND GLOBAL REPLACEMENT PROGRAM
  7.  
  8.                               By C.R.J. Currie
  9.         PURPOSE .............................................1
  10.  
  11.         PREPARATION..........................................2
  12.  
  13.         FORMAT OF STRING-LIST FILES..........................3
  14.  
  15.             a) Lists for Alternate Replacement...............3
  16.  
  17.             b) Lists for Global Replacement..................3
  18.  
  19.         FORMAT OF FILE-LIST FILE.............................4
  20.  
  21.         PARAGRAPH MARKER FILES...............................4
  22.  
  23.         RUNNING ALTERN.......................................4
  24.  
  25.         RUNNING THE FILEMAKE PROGRAM.........................5
  26.  
  27.         LIMITATIONS..........................................6
  28.  
  29.         HISTORY..............................................7
  30.  
  31.         SOFTWARE LICENCE.....................................8
  32.  
  33.         Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 1
  34.  
  35.  
  36.  
  37.                              ALTERN VERSION 2.2
  38.  
  39.                   ALTERNATE AND GLOBAL REPLACEMENT PROGRAM
  40.  
  41.                               By C.R.J. Currie
  42.  
  43.             1. PURPOSE
  44.  
  45.                ALTERN is a utility which helps to convert text files to
  46.                different formats or to prepare them for input to a
  47.                typesetter or output to a printer which your text editor
  48.                cannot drive.  It allows the global replacement of every
  49.                string in a prepared list, or the alternate replacement of
  50.                paired strings.  The last function is essential to convert
  51.                files prepared with a text editor such as Wordstar, which
  52.                uses 'toggles' to change text emphasis or type size, to a
  53.                format which requires that each style or size be overtly
  54.                specified.
  55.  
  56.                     Most text editors cannot cope with alternate
  57.                replacement, with bulk replacement of a series of strings at
  58.                once, or with automatic replacement throughout a set of
  59.                files.  Some cannot even replace their own control codes.
  60.                ALTERN can do all that.  It doesn't change your original
  61.                file, but makes a modified copy with the extension .COD.
  62.  
  63.                     For example a single run could replace every occurrence
  64.                of GOAT by ELEPHANT, every carriage return by a linefeed
  65.                with the 8th bit set, every odd-numbered occurrence of CAT
  66.                by DOG, and every even-numbered occurrence of CAT by SHEEP,
  67.                in each one of 100 files.
  68.  
  69.                     ALTERN uses single-character input and processes text a
  70.                paragraph at at time. The default paragraph marker is the
  71.                carriage return -- linefeed sequence (0D0A hex), but files
  72.                in formats which use other markers can be read and written.
  73.  
  74.                     ALTERN can also search e.g. Wordstar files for strings
  75.                in which some bytes may or may not have the eighth bit set,
  76.                and replace them.  Version 2.2 cannot search independently
  77.                of case: REAGAN and Reagan are treated as different strings.
  78.         Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 2
  79.  
  80.  
  81.             2. PREPARATION
  82.  
  83.                ALTERN requires two prepared files, held in the current
  84.                directory, listing codes for replacement: one for those to
  85.                be replaced alternately, another for those to be replaced
  86.                globally. Even if you only want to do global replacements,
  87.                you must prepare a dummy list of alternate replacements (see
  88.                3 a) below).  If you want to convert more than one file at a
  89.                time, you will also need a file listing the files to be
  90.                converted.  If your input or output files are to have
  91.                non-standard paragraph markers you will need a further file
  92.                for each of the two possible markers.
  93.  
  94.                     These files must be ASCII text files and can be
  95.                prepared with a text editor, such as Wordstar in
  96.                Non-Document mode, which can write ASCII files, or by
  97.                copying the console output to a file.  If you need to handle
  98.                strings which include characters that cannot be typed from
  99.                the keyboard, use the FILEMAKE utility to create the file or
  100.                files which list those strings.  Your text editor should be
  101.                able to load the resulting files so that you can add further
  102.                strings to the lists.
  103.  
  104.                     Strings which include double quotation marks (") MUST
  105.                NOT be included in the lists, but you can type them in while
  106.                running ALTERN.
  107.  
  108.                     The prepared lists, and the files to be converted, must
  109.                be in the current directory unless you have set a data path
  110.                with DPATH or some equivalent utility.
  111.  
  112.                     The order of sets of strings in the string-list files
  113.                is significant. That feature can be used to achieve complex
  114.                or tricky replacements: e.g. you can replace 11/21 by some
  115.                special code to print it as a fraction, and then replace 1/2
  116.                by another special code, in a single run. Doing it the other
  117.                way round will give erroneous output.
  118.         Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 3
  119.  
  120.  
  121.             3. FORMAT OF STRING-LIST FILES
  122.                a) LISTS FOR ALTERNATE REPLACEMENT
  123.  
  124.                   Each line should include a string to be replaced and the
  125.                   first and second replacements. Each string should be
  126.                   inclosed in double quotation marks and separated by a comma
  127.                   from the next. The last line of the file should consist of
  128.                   the word END in upper case. Example:
  129.  
  130.                   "CAT","DOG","SHEEP"
  131.                   ",",";","."
  132.                   END
  133.  
  134.                   In this example, all occurrences of CAT in the input file or
  135.                   files will be replaced alternately by DOG and SHEEP in the
  136.                   output file or files, and all commas will be replaced
  137.                   alternately by semicolons and full stops.
  138.  
  139.                   If you only want a dummy alternate-replacement file, type
  140.                   only one line of strings, all of which should be the same.
  141.  
  142.                   Example:
  143.  
  144.                   "A","A","A"
  145.                   END
  146.  
  147.                b) LISTS FOR GLOBAL REPLACEMENT
  148.  
  149.                   Each line should include a string to be replaced and the
  150.                   string to replace it. Each string should be inclosed in
  151.                   double quotation marks and the first should be separated by
  152.                   a comma from the next. The last line of the file should
  153.                   consist of the word END in upper case. Example:
  154.  
  155.                   "GOAT","ELEPHANT"
  156.                   "*",","
  157.                   END
  158.  
  159.                   In this example, all occurrences of GOAT in the input file
  160.                   or files will be replaced by ELEPHANT in the output file or
  161.                   files, and all asterisks will be replaced by commas.
  162.         Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 4
  163.  
  164.  
  165.             4. FORMAT OF FILE-LIST FILE
  166.  
  167.                  The list of files to be converted should consist simply of
  168.                  one filespec on each line. Example:
  169.  
  170.                  CHUMLEY.TXT
  171.                  DINGBAT
  172.                  FILE3.DAT
  173.  
  174.             5.  PARAGRAPH MARKER FILES
  175.  
  176.                If your input or output files need a paragraph marker other
  177.                than the default, you can put them in two files in the
  178.                current directory which MUST be called PARIN and PAROUT
  179.                respectively. ALTERN always searches the directory for those
  180.                files and only uses the defaul